fix(location): use native cached location fallback - #339

关联 Issue 与前置工作

Closes #338

本 PR 为 Android 增加 native last-known location 兜底。当 Expo 缓存或实时定位不可用时，语音握手和 geofence 仍可使用符合时效与精度要求的系统缓存位置；定位不可用或响应过慢时，不阻塞语音连接。

当前提交：

6c43662 fix(location): use native cached location fallback

当前分支：

codex/location-native-fallback

背景与目标

Android 系统可能已经保存了可用的 last-known location，但 Expo getCurrentPositionAsync 仍可能返回 ERR_CURRENT_LOCATION_IS_UNAVAILABLE。此前业务无法继续读取系统缓存位置，导致语音握手和 geofence 初始化获得 null；实时定位响应较慢时，还会延迟语音连接。

本 PR 目标：

• 增加 Android native cached location 数据源；
• 将 native fallback 接入语音和 geofence 定位流程；
• 只接受 60 秒内、精度不超过 200 米的有效缓存；
• 将语音启动阶段的定位等待上限缩短到 500ms；
• 避免权限或定位 API 异常形成未捕获的 Promise rejection；
• 提供 development build 真机定位探针。

完整流程

位置获取流程：

业务请求位置
  -> 读取 Expo 短期缓存
  -> Expo 缓存不可用时读取 Android native last-known location
  -> 校验坐标、观测时间和精度
  -> native 缓存合格时立即返回，并异步刷新 Expo current position
  -> native 缓存不可用时等待 Expo current position
  -> 所有来源均不可用时安全返回 null

语音启动流程：

定位在 500ms 内返回
  -> 将位置附加到语音握手

定位超过 500ms 或失败
  -> 本次 location sample 使用 null
  -> 语音连接继续启动

主要改动

Android native location

新增 TimeflowLocation native module：

• 从 network、passive、gps 和 fused provider 读取 last-known location；
• provider 即使处于禁用状态，也继续尝试读取系统保留的缓存；
• 单个 provider 不存在或读取异常时安全跳过；
• 只接受坐标合法、观测时间有效、缓存年龄不超过 60 秒且精度不超过 200 米的样本；
• 多个样本优先选择观测时间更新的位置，时间相同时选择精度更高的位置；
• 缺失时间不会被替换为当前时间，缺失或非法精度不会被替换为 0 米；
• 生产日志只记录 provider、缓存年龄和精度，不输出经纬度。

涉及文件：

• LocationModule.kt
• LocationSnapshotReader.kt
• LocationSnapshotSelector.kt
• AlarmPackage.kt
• Android module manifest

JavaScript native fallback

新增 NativeLocationFallback.ts：

• 调用 TimeflowLocation native module；
• 将原生 payload 映射为统一的 LocationSample；
• 原生模块不存在、调用失败、字段缺失或坐标非法时返回 null；
• 不在生产日志中输出精确经纬度。

Expo location provider

更新 ExpoLocationProvider.ts：

• 优先使用 Expo 短期缓存；
• Expo 缓存不可用时读取 native cached location；
• native 缓存命中后立即返回，并在后台刷新 Expo current position；
• native 缓存不可用时回退到 Expo 实时定位；
• 定位失败时返回 null，不主动弹出权限请求。

Geofence monitor

更新 ExpoLocationMonitor.ts：

• Expo current position 失败时回退 native cached location；
• native 缓存命中后更新 lastSample；
• 前台定位权限未授予时跳过采样；
• 后台权限状态读取失败时跳过区域同步；
• 在异步调用边界处理拒绝，避免未捕获异常。

Assistant conversation

更新：

• AssistantConversationService.ts
• AssistantContinuousConversationService.ts

将语音启动阶段的定位等待上限从 2000ms 调整为 500ms。定位超时只省略本次位置，不阻塞语音连接。

Development build

增加：

• expo-dev-client；
• timeflow URL scheme；
• development startup location probe；
• Android native module 真机验证入口。

精确坐标仅允许由受 __DEV__ 和 EXPO_PUBLIC_LOCATION_PROBE_ON_START 双重控制的开发探针输出。

验收行为

测试覆盖

新增或更新：

• LocationSnapshotReaderTest.java
• LocationSnapshotSelectorTest.java
• nativeLocationFallback.test.ts
• expoLocationProvider.test.ts
• expoLocationMonitor.test.ts
• AssistantConversationService.test.ts
• AssistantContinuousConversationService.test.ts

覆盖内容：

• provider 禁用时仍读取系统缓存；
• provider 读取异常时安全跳过；
• 多 provider 最新时间和同时间精度选择；
• 60 秒缓存时效与 200 米精度边界；
• 过期、未来、缺失时间和非法精度过滤；
• native payload 映射、空结果、异常和非法坐标；
• Expo 缓存、native fallback 与实时定位 fallback；
• geofence current position 失败后的 native fallback；
• 慢定位不阻塞语音连接；
• native fallback 命中时不输出精确坐标。

当前验证结果

本地验证：

• npm run lint
• npm run typecheck
• Vitest：9 files，87 tests passed
• Jest：67 suites，631 tests passed
• ./gradlew :timeflow-alarm:testDebugUnitTest：BUILD SUCCESSFUL
• git diff --check
• 远端分支 SHA 与本地提交一致

GitHub CI：

• Backend (lint, types, tests)
• Backend (migrations)
• Frontend (lint, types, build)
• codecov/patch

范围与非目标

本 PR 不处理：

• 完整后台定位授权流程；
• 强制申请 ACCESS_BACKGROUND_LOCATION；
• geofence enter/exit 状态机调整；
• 保证每次获得实时 GPS 坐标；
• iOS native cached location；
• 通用定位缓存策略重构；
• GitHub Actions Node.js 20 弃用警告；
• docker-compose.yml 配置调整。

风险与兼容性

• last-known location 仍是缓存数据，但本 PR 将可用范围限制为 60 秒内且精度不超过 200 米；
• 不同 Android 设备可用的 provider 可能不同，缺失或不可访问的 provider 会被跳过；
• 新增 native module 后需要重新构建 development build，Expo Go 不包含该模块；
• geofence 后台运行仍受 Android 后台定位权限约束；
• 生产日志不再输出经纬度，真机坐标诊断需要显式启用开发探针。

Review Checklist

• PR 已通过 Closes #338 关联 Issue。
• Diff 与 Issue 范围一致。
• docker-compose.yml 未包含在 PR 中。
• 已处理禁用 provider 的 review comment。
• 已增加 native 缓存时效与精度门槛。
• 已移除生产路径中的精确坐标日志。
• TypeScript、ESLint、前端测试和 Android native 测试通过。
• GitHub CI 和 Codecov 通过。
• Android development build 已验证 native cached location。